fix(spec): make what collectFlowGraphs RETURNS match its declared FlowNodeParsed[] - #16922

Fixes #16752

collectFlowGraphs declares each FlowGraph.nodes as readonly FlowNodeParsed[] and then pushed the list verbatim. That list is one the walk picks up itself out of a container's open z.record config, after an Array.isArray that proves the LIST and never its MEMBERS — so an empty item in a YAML nodes: list under a loop body reached a returned graph as null. No coercion at a call site could prevent it, which is the ground on which triage routed this producer-side: 「无caller-side discipline 可以触及一个 producer 自己从开放 z.record 里挑出来的数组」.

Premise re-derived on today's origin/main before writing

The card was measured on 7c12e475. PR #16825 (#16134) landed since, so both halves were re-measured against the merge base:

Driving the built dist/ over five non-record shapes and seven nestings, counting graphs whose nodes hold a non-record:

BEFORE  null  | d=0 badGraphs=1 | d=1 badGraphs=1 | d=2 badGraphs=1 | d=30 badGraphs=1 | d=31 badGraphs=1 | d=32 badGraphs=1 | d=33 badGraphs=0
AFTER   null  | d=0 badGraphs=0 | d=1 badGraphs=0 | d=2 badGraphs=0 | d=30 badGraphs=0 | d=31 badGraphs=0 | d=32 badGraphs=0 | d=33 badGraphs=0

Identical rows for undefined, a string, a number and an array. ⭐ The leak is at every depth, not only at the MAX_REGION_DEPTH ceiling the card identified — visit pushed nodes verbatim and merely skipped non-records while walking, so the ceiling is one route in and not the only one. d=33 reads 0 because the innermost region sits past the ceiling and is never visited at all.

The change

Four lines of production code in packages/spec/src/automation/control-flow.zod.ts:

• Filter what is handed out. const kept = nodes.filter((node) => isRegionDict(node)); and push kept only when something was actually dropped, so a well-formed flow keeps array identity and allocates nothing — copy-on-write, as parseFlowNodeRegions already is.
• Skip what is walked, through the same predicate. The inline three-clause test became if (!isRegionDict(node)) return;. One spelling for both, so the two cannot drift. This also stops admitting an array, which typeof raw === 'object' did.
• path stays indexed over the RAW list. The forEach still runs over nodes, never kept: graph.path anchors a Zod issue where the author wrote the node, so a drop must not renumber the siblings behind it.

⛔ Not a looser signature. The declared input and FlowGraph's field types are untouched — widening was the direction #15793 refused on the anti-AI-error axis, and this is the opposite move: the producer keeps a promise it had already made. ⛔ Not a throw either: this walk runs inside FlowSchema's parse, where a TypeError escapes safeParse instead of becoming an issue, so the repair is a drop and a skip.

The RESIDUAL_THROWS ledger — re-measured per row, not assumed

The card said the two #16752 rows come out. Because defect 1's throw was already gone, which rows are still earned was measured before deleting any: the suite was run with all four rows still present against the rebuilt producer, and the assertion is exact in both directions, so it named them itself.

The two kept rows are #16751's: lint-flow-patterns.ts reads flow.nodes itself at :1426, which a producer repair cannot reach. Its two graph.nodes casts at :456 / :1522 are now covered from the producer side, and the docblock is corrected to say exactly that, so the next reader knows what is left to repair there. The run with the rows still present:

Tests  2 failed | 326 passed (328)
 FAIL  flows[].nodes[].config.body.nodes > with null > throws out of no rule but the ones still filed as broken
 FAIL  flows[].nodes[].config.body.nodes > with undefined > throws out of no rule but the ones still filed as broken
AssertionError: expected [] to deeply equal [ 'lintFlowPatterns', …(1) ]

After removing exactly those two: Tests 328 passed (328).

Ablation — direction predicted before it was run

Predicted red: 15 hands out only records cases (5 shapes x 3 nestings) plus 5 anti-vacuity cases = 20 failures, with the safeParse, path and identity pins staying green because they pin properties the unfixed code also had.

Run from the committed state, mutation = the whole producer file put back to the merge-base content, restore under trap ... EXIT INT TERM using git checkout HEAD -- PATH (which resets index and tree; a bare git checkout -- would take the content back out of the polluted index):

pre-mutation   'const kept = nodes.filter': 1    'graphs.push({ scope, path, nodes, edges });': 0
post-mutation  'const kept = nodes.filter': 0    'graphs.push({ scope, path, nodes, edges });': 1
blob now=7a0539c4150a28642a186cffcb022976ae470142  head=91919189b678c513bbb64749468658538e000085

ABLATION_TEST_EXIT=1
 Test Files  1 failed (1)
      Tests  20 failed | 24 passed (44)

restore: blob back=91919189b678c513bbb64749468658538e000085 == head
         git diff HEAD  []      git status --porcelain  []

20 failed, exactly as predicted, and all 20 inside the new describe. Landing and restore are proven by anchor count and blob hash, never by an editor's exit code; every zero-hit grep above has its non-zero counterpart on the same corpus.

Verification — exit codes captured before any pipe

pnpm lint is the whole population, not a narrowing: the file count is read from eslint's own --format json output, and this repo runs one eslint.config.mjs which the config's own measured comment records as never enabling type-aware linting for any file.

No widening. check:api-surface and check:export-origins are both green inside check:generated: no export added, no signature loosened, no surface movement. The new predicate reuses the existing module-local isRegionDict.

node scripts/pm/dispatch-gates.mjs derives 76 families for these four paths; the 12 above were run locally and the remaining 64 are CI's farm. The derivation was re-run after merging origin/main in, because the first answer was flagged STALE TREE and would have been a well-formed answer about a tree nobody is on; the merged derivation is byte-identical to it.

验收备注

Noted, not filed:

• A dropped member renumbers its siblings inside graph.nodes. One consumer indexes it positionally: the duplicate-node-id rule in flow.zod.ts builds nodes[index] and a Zod issue path from that index. This is the same trade-off the four sibling repairs already made and that non-record-object-entry.test.ts records as accepted — 「a difference in the path, never in whether the object was judged」 — and it only arises inside a list that was already malformed, where the region carries a schema refusal of its own. graph.path, which is the anchor that matters, is pinned to stay raw-indexed. Not filed as a defect because the repo has already ruled on this exact shape; recorded here because no PR currently queued would otherwise carry it. Successor: none queued.
• The defensive (node as ...)?.id read in that same rule is now belt-and-braces for the null case, since graph.nodes holds only records. Dead-code tidying, deliberately not done here.
• control-flow.zod.ts's docblock (and the reference page generated from it) says the schema and validateControlFlow "cannot fight" and meet at ONE seam — #16134 makes both sentences false #16835 is unblocked and untouched. It owns the two module-docblock sentences at :61 ("cannot fight") and :63 ("one seam"); both are byte-identical to the merge base, and nothing in this diff sits above them, so their line numbers have not moved either.
• lint: two more flow-node-list readers throw on a non-record member — lintFlowPatterns and collectFlowVariableNames #16751 remains open and is not addressed here — its two kept ledger rows are the live record of that.

🤖 Generated with Claude Code

Generated by Claude Code

Clause-② declaration — added by the domain:spec execution seat, 2026-09-08T16:4xZ

Check Changeset refused this PR because the level axis was NOT MEASURED: a patch sits on @objectstack/spec, whose packages/*/src/** this diff moves, and no declaration was readable. The remedy the gate names is the declaration, ⛔ never dropping or regrading the changeset. Declaring it here, in the fixed spelling, as the claiming seat:

Clause-②: no
— this PR narrows what a published function hands out so that it matches the type it already
declares. It puts no new key on a published payload, adds no export (it reuses the existing
module-local isRegionDict), and moves no accept set: FlowSchema accepts and refuses exactly the
documents it did before, because the repair is drop-and-skip inside the parse rather than a new refusal.
check:generated is green across all 15 artifacts, check:api-surface and check:export-origins
included. ⇒ 拉回已声明契约, so the patch above stands.

The published contract text this no is required to quote

A no that deletes a refusal must cite the published text that already denied it — 「删已发布契约文本本就否定的误拒本身是 no;该 no 须引那段文本,缺引即读作缺申报」. This PR removes two throws. They were never verdicts:

① The declared return type. collectFlowGraphs declares FlowNodeParsed[]. Handing out a null member was already denied by that declaration — the defect is that the implementation did it anyway, at every nesting depth.

② The ledger that holds those throws says so itself, in its own docblock on packages/lint/src/non-record-object-entry.test.ts — and it names this card:

flows[].nodes[].config.body.nodes / validateStackExpressions + lintFlowPatterns (#16752) — neither rule's own reader is at fault here: both throw from INSIDE collectFlowGraphs, whose region walk reads node.config off a member of an inner list it checked only with Array.isArray. No coercion at either call site reaches that list, which is why #15793 stopped and filed the fork instead of widening a packages/spec contract to tolerate malformed members.

and, on removal being the expected outcome of the repair rather than a contract change:

a residual that gets fixed reds because its row is now a lie and has to go

⇒ The two removed rows are catalogued defects with a filed card, not designed refusals; and the alternative that would have been a clause-② yes — widening a packages/spec contract to tolerate malformed members — is precisely the direction #15793 rejected and this PR does not take.

⚠️ Stated openly rather than buried, because it is the one thing that could flip this reading: filtering graph.nodes renumbers surviving members inside that array, and flow.zod.ts's duplicate-node-id rule indexes it positionally. graph.path — the machine-consumed anchor — is kept raw-indexed and pinned by a test that stays green under ablation. The shift is confined to the nodes[i] label inside a list that was already malformed, and is the same trade-off the four sibling repairs made and that non-record-object-entry.test.ts already records as accepted. If a reviewer reads that renumbering as an accept-set movement, this declaration flips to yes and the PR parks; ⛔ nothing here was flipped to ready, enqueued, or given auto-merge.

Generated by Claude Code